<html>
<head>
<title>event handling in Jena 2</title>
<link href="../styles/doc.css" rel="stylesheet" type="text/css">
</head>
<body>
<h1>event handling in Jena 2</h1>

<b>id</b>: $Id: event-handler.html,v 1.7 2003/08/28 11:29:05 andy_seaborne Exp $
<br><b>author</b>: Chris Dollin

<h2>ModelChangedListener</h2>

In Jena 2 it is possible to monitor a Model for changes,
so that code can be run after changes are applied without
the coding for that Model having to do anything special.
We call these changes "events". (They have nothing to do
with GUI events.) This first design and implementation is
open for user comment and we may refine or reduce the
implemtation as more experience is gained with it.

<p>To monitor a Model, you must <i>register</i> a 
<i>ModelChangedListener</i> with that Model:

<pre>
    Model m = ModelFactory.createDefaultModel();
    ModelChangedListener L = new MyListener();
    m.register( L );
</pre>

<i>MyListener</i> must be an implementation of 
<i>ModelChangedListener</i>, for example:

<pre>
    class MyListener implements ModelChangedListener
        {
        public void addedStatement( Statement s ) 
            { System.out.println( ">> added statment " + s ); }
        public void addedStatements( Statement [] statements ) {}
        public void addedStatements( List statements ) {}
        public void addedStatements( StmtIterator statements ) {}
        public void addedStatements( Model m ) {}
        public void removedStatement( Statement s ) {}   
        public void removedStatements( Statement [] statements ) {}
        public void removedStatements( List statements ) {}
        public void removedStatements( StmtIterator statements ) {}
        public void removedStatements( Model m ) {}   
        }
</pre>

This listener ignores everything except the addition of single
statements to <i>m</i>; those it prints out. The listener has
a method for each of the ways that statements can be added to a Model:

<ul>
<li>as a single statement, Model::add(Statement)</li>
<li>as an element of an array of statements, Model::add(Statement[])</li>
<li>as an element of a list of statements, Model::add(List)</li>
<li>as an interator over statements, Model::add(StmtIterator)</li>
<li>as part of another Model, Model::add(Model)</li>
</ul>

<p>(Similarly for <i>delete</i>.)
</p>

<p>
The listener method is called when the statement(s) have been added to
the Model, if no exceptions have been thrown. It does not matter if the
statement was <i>already</i> in the Model or not; it is the act of
adding it that fires the listener. 

<p> 
There is no guarantee that the statement, array, list, or model that
is added or removed is the same one that is passed to the appropriate
listener method, and the <i>StmtIterator</i> will never be the same
one. However, in the current design:

<ul>
<li>a single Statement will be .equals to the original Statement</li>
<li>a List will be .equals to the original List</li>
<li>a Statement[] will be the same length and have .equal elements
     in the same order
     </li>
<li>a StmtIterator will deliver .equal elements in the same order</li>
<li>a Model will contain the same statements</li>
</ul>

We advise not relying on these ordering properties; instead assume
that for any bulk update operation on the model, the listener will
be told the method of update and the statements added or removed,
but that the order may be different and duplicate statements may
have been removed. 

<p>Note in particular that a Model with any Listeners will have
to record the complete contents of any <i>StmtIterator</i> that
is added or removed to the model, so that the Model and the
Listener can both see all the statements. 

<p>
Finally, there is no guarantee that <i>only</i> Statements etc added
through the Model API will be presented to the listener; any Triples
added to its underlying Graph will also be presented to the listener 
as statements.

<h2>Utility classes</h2>

The full Listener API is rather chunky and it can be inconvenient to
use, especially for the creation of inline classes. There are four
utility classes in <i>com.hp.hpl.jena.rdf.listeners:</i>

<ul>
<li><i>NullListener</i>. This class's methods do nothing.
This is useful when you want to subclass and intercept
only specific ways of updating a Model.
</li>

<li><i>ChangedListener</i>. This class only records whether some change
has been made, but not what it is. The method <i>hasChanged()</i>
returns <i>true</i> if some change has been made since the last call
of <i>hasChanged()</i> [or since the listener was created].
</li>

<li><i>StatementListener</i>. This class translates all bulk update calls
(ie the ones other than <i>addedStatement()</i> and 
<i>removedStatement()</i>) into calls to <i>addedStatement()/removedStatement()</i>
for each Statement in the collection. This allows statements to be tracked whether 
they are added one at a time or in bulk.
</li>

<li><i>ObjectListener</i>. This class translates all the listener calls into
<i>added(Object)</i> or <i>removed(Object)</i> as appropriate; it
is left to the user code to distinguish among the types of argument.
</li>
</ul>

<h2>when listeners are called</h2>

In the current implementation, listener methods are called immediately
the additions or removals are made, in the same thread as the one making
the update. If a model has multiple listeners registered, the order in
which they are informed about an update is unspecified and may change
from update to update. If any listener throws an exception, that exception
is thrown through the update call, and other listeners may not be informed
of the update.

<p>Hence listener code should be brief and exception-free if at all 
possible. 

<h2>registering and unregistering</h2>

<p>A listener may be registered with the same model multiple times. If 
so, it will be invoked as many times as it is registered for each update
event on the model. 

<p>A listener <i>L</i> may be <i>unregistered</i> from a Model using the
method <code>unregister(L)</code>. If <i>L</i> is not registered with
the model, nothing happens.

<p>If a listener is registered multiple times with the same model, each
<code>unregister()</code> for that listener will remove just one of the
registrations.

<h2>transactions and databases</h2>

In the current design, listeners are not informed of transaction boundaries,
and all events are fed to listeners as soon as they happen.

<p>In the current implementation, if an RDB model <i>M</i> is modified
by some other client of the database, those changes are not seen and thus 
are not reported to listeners.  

</body>
</html>
